Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?

We recently implemented a linting/code formatting overhaul, relying on ruff #156.
However, we are still missing linting/formatting for docstrings. Would be nice to have them all formatted in a uniform way.

What does this PR do?
It adds the "D" (pydocstyle) ruleset to the ruff config.
That enforces a bunch of rules on docstring formatting, and most problems are auto-fixed.
However, I had to fix lots of issues manually, because many of our existing docstrings were non-compliant.

The rules that necessitated most manual work were the ones stipulating that docstrings should start with a one-line short description ending in a period, optionally followed by a longer description (separated from the one-liner by 1 blank line), e.g.:

def foo(bar):
    """Perform some function (has to fit in one line).
    
    Here is the longer description which can extend over
    multiple lines.
    """

This is a bit restrictive and I had to rewrite a bunch of docstrings accordingly, but I like the consistent result we end up with.
Going forward this should be much less work, because we'll get immediate feedback on this via pre-commit, so no additional inconsistencies should creep in.

I relaxed the rules quite a bit for the tests folder, because those docstrings are not public-facing.

The relevant configuration changes are to be found in pyproject.toml. All the other diffs have to do with fixing issues encountered during pre-commit run --all-files.

How has this PR been tested?

Visually checked the locally rendered sphinx API docs.

Is this a breaking change?

No.

Does this PR require an update to the documentation?

No.

Checklist:

• The code has been tested locally
• Tests have been added to cover all new functionality
• The documentation has been updated to reflect any changes
• The code has been formatted with pre-commit